Skip to content

Add livetennisapi.reconcile for point gaps and score withdrawals - #8

Open
bensynapse wants to merge 1 commit into
mainfrom
feat/ws-frame-reconcile
Open

bensynapse wants to merge 1 commit into
mainfrom
feat/ws-frame-reconcile

Conversation

@bensynapse

Copy link
Copy Markdown
Member

Adds livetennisapi.reconcile for people who read the Live Tennis API live feed on their own socket or through webhooks. It makes no network calls of its own.

PushStream already repairs point gaps itself. The native /ws feed and webhook receivers had nothing, and score_withdrawn had no model anywhere in the SDK.

  • parse_frame(message) takes text, bytes or a dict and returns a typed frame: ScoreUpdate, PointUpdate, the new ScoreWithdrawn and PointTagUpdate (point_update), the break-point pair, or ControlFrame for anything else. Bad JSON, a non-object or a missing type raise FrameError.
  • PointSequencer drops repeated point frames and holds frames that arrive after a missing seq. gap(match_id) gives the after_seq to pass to get_match_points(), and fill() releases the held points in seq order, each once. A page on the reconstruction basis raises ValueError, because its numbering differs from the live stream.
  • ScoreBook keeps the newest score per match by sequence. A withdrawn or withheld frame drops the matching state and stops it coming back. A deferred one keeps it and flags it through verdict().

The README has a new section with an asyncio example.

How I checked it:

  • pytest -m "not contract": 291 passed (45 of them new, in tests/test_reconcile.py). They cover in-order, out-of-order and duplicate frames, a gap and its fill, score_withdrawn of each kind, and malformed input.
  • ruff check src/ tests/ and ruff format --check src/ are clean. mypy src/livetennisapi reports nothing in the new module (the 8 errors it shows are already on main).
  • scripts/truthcheck.sh passes.
  • I ran the README example against a local fake server that sent a gap, a repeat, a bad frame, a withdrawal and an error frame. It fetched the missing points over REST and printed them in order.

Not in this PR: LiveScoreStream still drops score_withdrawn and point_update frames without telling the caller, and the JS SDK has the same gap.

The push feed already repairs point gaps inside PushStream. Anyone on
the native /ws feed with their own socket, or taking webhooks, had to
write that bookkeeping by hand, and score_withdrawn had no model.

parse_frame() types a frame and raises FrameError on bad JSON.
PointSequencer drops repeated point frames and holds frames that arrive
after a missing seq. It reports the after_seq to fetch from
get_match_points() and releases points in seq order once a page fills
the gap. It refuses reconstruction pages, whose seq numbering differs.
ScoreBook keeps the newest score per match by sequence. It drops a
withdrawn or withheld state and flags a deferred one.

No I/O and no new dependency. LiveScoreStream is unchanged.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant